7.04. Справочник по Nginx

ДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНОВ РАЗРАБОТКЕ

Разработчику Архитектору Инженеру

Справочник по Nginx

Nginx — высокопроизводительный веб-сервер, прокси-сервер и балансировщик нагрузки с открытым исходным кодом. Он обрабатывает HTTP, HTTPS, SMTP, POP3, IMAP и поддерживает модульное расширение функциональности. Конфигурация Nginx осуществляется через текстовые файлы с использованием декларативного синтаксиса, основанного на блоках и директивах.

Конфигурационные файлы обычно расположены в /etc/nginx/. Основной файл — nginx.conf. Дополнительные конфигурации подключаются через директиву include.

Конфигурация состоит из контекстов (блоков), внутри которых задаются директивы. Каждая директива завершается точкой с запятой (;), за исключением блоков.

Уровни конфигурации (контексты)

Конфигурация Nginx строится иерархически. Существуют следующие уровни:

1. Главный контекст (`main`)

Это верхний уровень конфигурации, вне любых блоков. Здесь определяются глобальные параметры сервера.

Пример:

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

Директивы главного контекста

`user`

Задает имя пользователя и группу, от которых будут запускаться рабочие процессы.

Синтаксис: user user [group];
Значение по умолчанию: nobody nobody или nobody
Пример: user www-data;

`worker_processes`

Определяет количество рабочих процессов.

Синтаксис: worker_processes number | auto;
Значение по умолчанию: 1
auto автоматически устанавливает количество ядер CPU.
Рекомендуется устанавливать равным числу ядер процессора.

`worker_connections`

Устанавливает максимальное число одновременных соединений для одного рабочего процесса. Используется внутри блока events.

Синтаксис: worker_connections number;
Значение по умолчанию: зависит от системы, часто 512 или 1024
Максимальное значение ограничено системным лимитом ulimit -n.

`error_log`

Задает путь к файлу журнала ошибок и уровень детализации.

Синтаксис: error_log file [level];
Уровни: debug, info, notice, warn, error, crit, alert, emerg
Пример: error_log /var/log/nginx/error.log warn;

`pid`

Указывает путь к файлу PID-процесса главного процесса Nginx.

Синтаксис: pid file;
Пример: pid /run/nginx.pid;

`worker_rlimit_nofile`

Устанавливает лимит открытых файловых дескрипторов для рабочих процессов (через setrlimit()).

Синтаксис: worker_rlimit_nofile number;
Пример: worker_rlimit_nofile 65536;

`worker_cpu_affinity`

Привязывает рабочие процессы к конкретным CPU-ядрам.

Синтаксис: worker_cpu_affinity cpumask ...; или worker_cpu_affinity auto [mask];
Пример для 4 ядер: worker_cpu_affinity 0001 0010 0100 1000;

`timer_resolution`

Уменьшает частоту вызовов системных таймеров, повышая производительность при большом числе соединений.

Синтаксис: timer_resolution interval;
Пример: timer_resolution 100ms;

`worker_priority`

Устанавливает приоритет планировщика для рабочих процессов (значение nice).

Синтаксис: worker_priority number;
Диапазон: от -20 (высокий приоритет) до 19 (низкий)
Пример: worker_priority 0;

`ssl_engine`

Задает использование аппаратного SSL-ускорителя через OpenSSL ENGINE.

Синтаксис: ssl_engine device;
Пример: ssl_engine rdrand;

2. Контекст `events`

Блок events содержит настройки, связанные с обработкой сетевых соединений.

Пример:

events {
    worker_connections 4096;
    use epoll;
    multi_accept on;
}

Директивы блока `events`

`worker_connections`

Максимальное число одновременных соединений на один рабочий процесс.

Синтаксис: worker_connections number;
Пример: worker_connections 8192;

`use`

Выбирает метод обработки соединений (event method).

Синтаксис: use method;
Доступные методы: epoll (Linux), kqueue (BSD/macOS), select, poll
На Linux рекомендуется epoll.

`multi_accept`

Разрешает одному рабочему процессу принимать все новые соединения за один вызов accept().

Синтаксис: multi_accept on | off;
Значение по умолчанию: off
При включении может повысить производительность при высокой нагрузке.

`accept_mutex`

Включает мьютекс для распределения входящих соединений между рабочими процессами.

Синтаксис: accept_mutex on | off;
Значение по умолчанию: off (в современных версиях Nginx)
В старых версиях было on.

`accept_mutex_delay`

Задержка перед повторной попыткой получения мьютекса.

Синтаксис: accept_mutex_delay time;
Пример: accept_mutex_delay 500ms;

`debug_connection`

Включает режим отладки для указанных адресов.

Синтаксис: debug_connection address | CIDR;
Пример: debug_connection 192.168.1.0/24;

3. Контекст `http`

Основной блок для настройки HTTP-сервера. Содержит общие параметры, MIME-типы, логгирование, SSL и определения серверов (server).

Пример:

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;

    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

Директивы блока `http`

`include`

Включает внешние файлы конфигурации.

Синтаксис: include file | mask;
Пример: include /etc/nginx/sites-enabled/*;

`default_type`

Тип содержимого по умолчанию, если MIME-тип не определен.

Синтаксис: default_type mime-type;
Значение по умолчанию: text/plain
Часто используется: application/octet-stream

`types`

Определяет соответствие расширений файлов MIME-типам.

Синтаксис:

types {
    text/html html htm;
    image/jpeg jpeg jpg;
}

Обычно подключается из mime.types.

`log_format`

Определяет формат записей в access-лог.

Синтаксис: log_format name string ...;
Переменные: $remote_addr, $status, $request, $http_user_agent и другие

Пример:

log_format detailed '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct="$upstream_connect_time" '
                    'uht="$upstream_header_time" urt="$upstream_response_time"';

`access_log`

Включает ведение журнала доступа.

Синтаксис: access_log path [format [buffer=size] [flush=time] [if=condition]];
Пример: access_log /var/log/nginx/access.log main buffer=32k flush=1m;

`sendfile`

Включает системный вызов sendfile() для эффективной передачи файлов.

Синтаксис: sendfile on | off;
Значение по умолчанию: off
Рекомендуется включать: sendfile on;

`tcp_nopush`

Позволяет отправлять заголовки и данные одним пакетом при использовании sendfile.

Синтаксис: tcp_nopush on | off;
Работает только при включенном sendfile.
Рекомендуется: tcp_nopush on;

`tcp_nodelay`

Отключает алгоритм Нейгла, обеспечивая немедленную отправку данных.

Синтаксис: tcp_nodelay on | off;
Значение по умолчанию: on
Важно для интерактивных приложений (WebSocket, API).

`keepalive_timeout`

Устанавливает таймаут keep-alive соединений.

Синтаксис: keepalive_timeout timeout [header_timeout];
Пример: keepalive_timeout 65;
Второе значение — время, указанное в заголовке Keep-Alive.

`keepalive_requests`

Максимальное число запросов на одно keep-alive соединение.

Синтаксис: keepalive_requests number;
Значение по умолчанию: 100
Можно увеличить до 1000 или больше.

`reset_timedout_connection`

Сбрасывает соединение с помощью RST вместо корректного закрытия при таймауте.

Синтаксис: reset_timedout_connection on | off;
Может снизить потребление памяти при большом числе "зависших" клиентов.

`server_tokens`

Управляет отображением версии Nginx в заголовках ответа.

Синтаксис: server_tokens on | off | string;
При off заголовок Server содержит только nginx.
При string можно указать произвольную строку (требуется модуль ngx_http_core_module с патчем).

`client_max_body_size`

Максимальный размер тела запроса клиента.

Синтаксис: client_max_body_size size;
Значение по умолчанию: 1m
Пример: client_max_body_size 100m;

`client_body_buffer_size`

Размер буфера для тела запроса клиента.

Синтаксис: client_body_buffer_size size;
По умолчанию: 8k или 16k (в зависимости от архитектуры)
Если тело больше — сохраняется во временный файл.

`client_body_temp_path`

Путь для временных файлов тела запроса.

Синтаксис: client_body_temp_path path [level1 [level2 [level3]]];
Пример: client_body_temp_path /var/cache/nginx/client_temp 1 2;

`client_header_buffer_size`

Размер буфера для заголовков запроса.

Синтаксис: client_header_buffer_size size;
Значение по умолчанию: 1k
Для больших заголовков (например, с куками) может потребоваться увеличение.

`large_client_header_buffers`

Число и размер буферов для больших заголовков.

Синтаксис: large_client_header_buffers number size;
Пример: large_client_header_buffers 4 16k;

`client_body_in_file_only`

Принудительно сохраняет тело запроса во временный файл.

Синтаксис: client_body_in_file_only on | off | clean;
clean удаляет файл после обработки запроса.
Используется в прокси-режиме для предотвращения переполнения памяти.

`gzip`

Включает сжатие ответов.

Синтаксис: gzip on | off;
Значение по умолчанию: off

`gzip_vary`

Добавляет заголовок Vary: Accept-Encoding.

Синтаксис: gzip_vary on | off;
Рекомендуется включать при использовании gzip.

`gzip_min_length`

Минимальный размер ответа для сжатия.

Синтаксис: gzip_min_length length;
Значение по умолчанию: 20
Ответы меньше этого размера не сжимаются.

`gzip_comp_level`

Уровень сжатия (от 1 до 9).

Синтаксис: gzip_comp_level level;
Значение по умолчанию: 1
Высокие значения дают лучшее сжатие, но требуют больше CPU.

`gzip_types`

MIME-типы, для которых применяется сжатие.

Синтаксис: gzip_types mime-type ...;

Пример:

gzip_types
    text/plain
    text/css
    application/json
    application/javascript
    text/xml
    application/xml
    application/xml+rss
    text/javascript;

`gzip_proxied`

Определяет, когда применять сжатие для проксированных ответов.

Синтаксис: gzip_proxied off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any ...;
any — сжимать все проксированные ответы.

`gzip_disable`

Отключает сжатие для определенных User-Agent.

Синтаксис: gzip_disable regex ...;
Пример: gzip_disable "MSIE [1-6]\.";

`open_file_cache`

Кэширует метаданные открытых файлов.

Синтаксис: open_file_cache max=N [inactive=time];
Пример: open_file_cache max=1000 inactive=20s;

`open_file_cache_valid`

Интервал проверки актуальности записей в кэше.

Синтаксис: open_file_cache_valid time;
Пример: open_file_cache_valid 30s;

`open_file_cache_min_uses`

Минимальное число обращений за время inactive, чтобы файл остался в кэше.

Синтаксис: open_file_cache_min_uses number;
Пример: open_file_cache_min_uses 2;

`open_file_cache_errors`

Кэшировать ли информацию об ошибках открытия файлов.

Синтаксис: open_file_cache_errors on | off;
При on ошибки типа "файл не найден" кэшируются.

`resolver`

Задает DNS-резолверы для разрешения имён.

Синтаксис: resolver address ... [valid=time] [ipv6=on|off];
Пример: resolver 8.8.8.8 8.8.4.4 valid=30s;

`resolver_timeout`

Таймаут для DNS-запросов.

Синтаксис: resolver_timeout time;
Пример: resolver_timeout 5s;

`variables_hash_max_size`

Максимальный размер хеш-таблицы для переменных.

Синтаксис: variables_hash_max_size size;
Значение по умолчанию: 1024

`variables_hash_bucket_size`

Размер корзины хеш-таблицы переменных.

Синтаксис: variables_hash_bucket_size size;
Должен быть степенью двойки.

`server_names_hash_max_size`

Максимальный размер хеш-таблицы для имен серверов.

Синтаксис: server_names_hash_max_size size;
Увеличивается при большом числе server_name.

`server_names_hash_bucket_size`

Размер корзины хеш-таблицы имен серверов.

Синтаксис: server_names_hash_bucket_size size;
Значение по умолчанию: 32 или 64

`map`

Создает переменную на основе другой переменной.

Синтаксис:

map $source_variable $new_variable {
    default value;
    pattern1 value1;
    pattern2 value2;
}

Пример:

map $http_user_agent $is_mobile {
    default 0;
    "~*android|iphone|ipod" 1;
}

`geo`

Определяет переменную на основе IP-адреса клиента.

Синтаксис:

geo [$address] $variable {
    default value;
    range value;
}

Пример:

geo $remote_addr $country {
    default ZZ;
    1.0.0.0/24 AU;
    2a02::/32 RU;
}

`limit_conn_zone`

Определяет зону разделяемой памяти для ограничения числа соединений.

Синтаксис: limit_conn_zone key zone=name:size;
Пример: limit_conn_zone $binary_remote_addr zone=addr:10m;

`limit_req_zone`

Определяет зону разделяемой памяти для ограничения частоты запросов.

Синтаксис: limit_req_zone key zone=name:size rate=rate;
Пример: limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

`upstream`

Определяет группу backend-серверов для проксирования.

Синтаксис:

upstream name {
    server address [parameters];
    ...
}

Подробнее рассмотрим в разделе Upstream.

Блок `server`

Блок server определяет виртуальный хост — отдельный сайт или приложение, обслуживаемое Nginx. Он может содержать настройки для HTTP или HTTPS, слушать разные порты и IP-адреса, а также обрабатывать запросы по доменным именам.

Контекст

Допустим только внутри блока http.

Пример базового сервера:

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html index.php;
}

Основные директивы блока `server`

`listen`

Указывает адрес и порт, на которых сервер принимает соединения.

Синтаксис:
listen address[:port] [default_server] [ssl] [http2] [proxy_protocol] ...;
или
listen port [default_server] [ssl] [http2] ...;

Примеры:

listen 80;
listen 192.168.1.10:8080;
listen 443 ssl http2;
listen [::]:80;

Параметры:
- default_server — сервер по умолчанию, если не совпадает ни один server_name.
- ssl — включает SSL/TLS для этого слушателя.
- http2 — включает поддержку HTTP/2.
- proxy_protocol — ожидает PROXY-протокол (например, от HAProxy).

`server_name`

Задает доменные имена, для которых применяется данный блок.

Синтаксис: server_name name1 [name2 ...];
Поддерживает:
- Точные совпадения: example.com
- Звёздочки: *.example.com
- Регулярные выражения: ~^www\d+\.example\.com$
Приоритет сопоставления:
1. Точное совпадение
2. Длиннейший префикс с * в начале (*.example.com)
3. Длиннейший префикс с * в конце (www.*)
4. Первое совпадение по регулярному выражению

Пример:

server_name example.com *.example.org ~^(?<subdomain>.+)\.test\.local$;

`root`

Указывает корневую директорию для поиска файлов.

Синтаксис: root path;
Пример: root /var/www/html;
Используется в связке с location и $uri.

`index`

Определяет файлы, которые будут использоваться как индексные (по умолчанию).

Синтаксис: index file ...;
Пример: index index.html index.php default.htm;

`error_page`

Настраивает страницы ошибок.

Синтаксис: error_page code ... [=[response]] uri;

Примеры:

error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
error_page 403 =404 /forbidden.html;

`try_files`

Проверяет существование файлов в указанном порядке и выполняет внутреннее перенаправление.

Синтаксис: try_files file ... uri; или try_files file ... =code;

Примеры:

try_files $uri $uri/ /index.php?$query_string;
try_files $uri @fallback;
try_files $uri =404;

`client_max_body_size`

Переопределяет глобальное значение для данного сервера.

Пример: client_max_body_size 50M;

`ssl_certificate` и `ssl_certificate_key`

Указывают пути к SSL-сертификату и закрытому ключу.

Пример:

ssl_certificate /etc/nginx/ssl/example.com.crt;
ssl_certificate_key /etc/nginx/ssl/example.com.key;

`ssl_protocols`, `ssl_ciphers`, `ssl_prefer_server_ciphers`

Контролируют безопасность SSL/TLS.

Пример:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
ssl_prefer_server_ciphers off;

`return`

Выполняет немедленный возврат ответа клиенту.

Синтаксис: return code [text]; или return code URL;

Примеры:

return 403;
return 301 https://$host$request_uri;
return 200 "OK";

`rewrite`

Выполняет перезапись URI.

Синтаксис: rewrite regex replacement [flag];
Флаги:
- last — завершить текущий цикл перезаписи и начать новый поиск location
- break — завершить перезапись, не искать новый location
- redirect — вернуть 302
- permanent — вернуть 301
Пример:
```
rewrite ^/old/(.*)$ /new/$1 permanent;
```

Блок `location`

Блок location определяет правила обработки запросов по URI. Он может содержать любые директивы, допустимые в контексте server.

Типы матчинга

Точный префикс — location = /exact
Префиксный матч — location /prefix
Регистронезависимый префикс — location ^~ /prefix
Регулярное выражение — location ~ pattern (чувствительно к регистру)
Регистронезависимое регулярное выражение — location ~* pattern

Приоритет обработки

Точный матч (=)
Префиксный матч с ^~
Регулярные выражения (в порядке объявления)
Обычный префиксный матч (самый длинный)

Примеры:

location = / {
    # только точный запрос к "/"
}

location ^~ /static/ {
    # все URI, начинающиеся с /static/, без проверки регулярок
}

location ~ \.php$ {
    # PHP-файлы
}

location / {
    # fallback
}

Полезные директивы внутри `location`

`alias`

Заменяет часть URI на указанный путь.

Отличие от root: root добавляет URI к пути, alias заменяет его.

Пример:

location /assets/ {
    alias /var/www/static/;
    # запрос /assets/logo.png → /var/www/static/logo.png
}

`deny` / `allow`

Контролируют доступ по IP.

Пример:

location /admin/ {
    allow 192.168.1.0/24;
    deny all;
}

`auth_basic`

Включает HTTP Basic Auth.

Пример:

location /secure/ {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

`add_header`

Добавляет заголовок в ответ.

Пример:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Важно: add_header в дочернем блоке переопределяет заголовки родителя, а не дополняет их.

`expires`

Устанавливает заголовок Cache-Control и Expires.

Пример:

location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

`internal`

Делает location доступным только для внутренних перенаправлений (например, из error_page, rewrite, try_files).

Пример:

location /internal/ {
    internal;
    root /var/private;
}

Проксирование

Nginx часто используется как обратный прокси для передачи запросов бэкендам.

`proxy_pass`

Передаёт запрос на бэкенд.

Пример:

location /api/ {
    proxy_pass http://backend;
}

Особенности:
- Если URI указан в proxy_pass, он заменяет совпадающую часть.
- Если нет — URI передаётся как есть.

Передача заголовков

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Таймауты

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Буферизация

proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 8 4k;

`proxy_redirect`

Исправляет заголовки Location и Refresh от бэкенда.

Пример:

proxy_redirect http://backend/ https://$host/;

FastCGI (для PHP)

Для запуска PHP через PHP-FPM используется FastCGI.

Пример:

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Ключевые параметры:

fastcgi_pass — адрес FPM-процесса
SCRIPT_FILENAME — обязательный параметр для PHP
fastcgi_param — передача переменных окружения

Upstream и балансировка нагрузки

Блок upstream определяет группу серверов, на которые можно перенаправлять запросы. Он используется в связке с proxy_pass, fastcgi_pass, uwsgi_pass, grpc_pass и другими директивами проксирования.

Контекст

Допустим только внутри блока http.

Пример:

upstream backend {
    server 10.0.0.1:8080 weight=3;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080 backup;
}

Параметры сервера

weight=number — задаёт вес сервера (по умолчанию 1). Чем выше вес, тем чаще запросы направляются на этот сервер.
max_conns=number — максимальное число одновременных активных соединений (требуется коммерческая версия или recent open source).
max_fails=number — количество неудачных попыток до признания сервера недоступным.
fail_timeout=time — время, в течение которого сервер считается неработоспособным после max_fails ошибок.
backup — сервер используется только если все основные недоступны.
down — помечает сервер как нерабочий (для обслуживания).

Методы балансировки

По умолчанию используется round-robin (циклическое распределение). Другие методы:

`least_conn`

Выбирает сервер с наименьшим числом активных соединений.

upstream backend {
    least_conn;
    server 10.0.0.1;
    server 10.0.0.2;
}

`ip_hash`

Гарантирует, что запросы с одного IP всегда идут на один и тот же сервер (полезно для сессий без кук).

upstream backend {
    ip_hash;
    server 10.0.0.1;
    server 10.0.0.2;
}

Не совместим с weight и backup в некоторых версиях.

`hash key [consistent]`

Распределяет запросы по хешу от заданного ключа (например, $request_uri).

upstream backend {
    hash $request_uri consistent;
    server 10.0.0.1;
    server 10.0.0.2;
}

consistent — включает алгоритм consistent hashing, минимизирующий перераспределение при добавлении/удалении серверов.

`random`

Выбирает случайный сервер. Можно указать два сервера и выбрать из них по least_conn или least_time.

upstream backend {
    random two least_time=header;
    server 10.0.0.1;
    server 10.0.0.2;
}

Проверка работоспособности (health checks)

В open source версии проверка осуществляется пассивно через max_fails и fail_timeout.
Активные health checks доступны только в Nginx Plus.

Ограничение частоты запросов и соединений

`limit_req` — ограничение по скорости запросов

Используется вместе с limit_req_zone.

Пример:

http {
    limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;

    server {
        location /api/ {
            limit_req zone=perip burst=5 nodelay;
        }
    }
}

burst=5 — разрешает накопление до 5 запросов в «очереди».
nodelay — отправляет все запросы из очереди сразу, без задержки.
Без nodelay — избыточные запросы обрабатываются с задержкой, чтобы соблюсти rate.

`limit_conn` — ограничение числа одновременных соединений

Пример:

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    server {
        location /download/ {
            limit_conn addr 1;
        }
    }
}

Ограничивает до 1 соединения с одного IP в /download/.

Глобальные ограничения

Можно применять на уровне server или http:

limit_conn addr 10;
limit_req zone=perip burst=20;

Кэширование

`proxy_cache` — кэширование проксированных ответов

Настройка зоны кэша:

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=10g
                 inactive=60m use_temp_path=off;

levels=1:2 — структура каталогов (например, /a/bc/abcdef...)
keys_zone=my_cache:10m — имя и размер метаданных в RAM
max_size=10g — максимальный размер кэша на диске
inactive=60m — файлы, не запрашиваемые 60 минут, удаляются
use_temp_path=off — запись напрямую в кэш, минуя временный файл

Использование:

location / {
    proxy_cache my_cache;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_use_stale error timeout updating http_500;
    proxy_cache_revalidate on;
    add_header X-Cache-Status $upstream_cache_status;
}

$upstream_cache_status — переменная: HIT, MISS, EXPIRED, STALE, BYPASS
proxy_cache_use_stale — использовать устаревший кэш при ошибках бэкенда
proxy_cache_revalidate — отправлять If-Modified-Since при обновлении

`fastcgi_cache` — кэширование FastCGI-ответов (например, PHP)

Аналогично proxy_cache, но с директивами fastcgi_cache_*.

fastcgi_cache_path /var/cache/nginx/fcgi levels=1:2 keys_zone=fcgi:10m inactive=60m;
location ~ \.php$ {
    fastcgi_cache fcgi;
    fastcgi_cache_valid 200 5m;
    fastcgi_cache_use_stale error timeout;
    add_header X-FastCGI-Cache $upstream_cache_status;
    ...
}

Переменные Nginx

Переменные начинаются с $ и могут использоваться в большинстве директив.

Встроенные переменные

Переменная	Описание
`$uri`	Нормализованный URI (без аргументов)
`$request_uri`	Полный URI с аргументами
`$args`	Строка запроса (query string)
`$arg_name`	Значение параметра `name` из строки запроса
`$host`	Заголовок `Host` из запроса
`$http_user_agent`	User-Agent клиента
`$remote_addr`	IP-адрес клиента
`$binary_remote_addr`	Бинарное представление IP (экономит память в зонах)
`$scheme`	Протокол (`http` или `https`)
`$request_method`	Метод запроса (`GET`, `POST` и т.д.)
`$status`	HTTP-статус ответа
`$request_time`	Время обработки запроса (в секундах, с точностью до мс)
`$upstream_response_time`	Время ответа от бэкенда
`$sent_http_content_type`	Значение заголовка `Content-Type` в ответе

Создание пользовательских переменных

Через map или set.

`map` — глобально, эффективно:

map $http_accept_language $lang {
    default en;
    ~*ru ru;
    ~*de de;
}

`set` — внутри `server` или `location`:

location / {
    set $custom_var "value";
    return 200 $custom_var;
}

set менее производителен, так как выполняется при каждом запросе.

Модульные директивы

`ngx_http_geo_module` — определение переменной по IP

geo $country {
    default        ZZ;
    1.0.0.0/24     AU;
    2a02::/32      RU;
    include        /etc/nginx/geo.conf;
}

`ngx_http_map_module` — преобразование значений

map $status $loggable {
    ~^[23]  0;  # не логировать 2xx и 3xx
    default 1;
}
access_log /var/log/nginx/access.log main if=$loggable;

`ngx_http_split_clients_module` — A/B тестирование

split_clients "${remote_addr}" $variant {
    50% ".v1";
    50% ".v2";
}

Используется для выбора разных upstream или root.

Логирование и мониторинг

Расширенный формат лога

log_format detailed '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   'rt=$request_time uct="$upstream_connect_time" '
                   'uht="$upstream_header_time" urt="$upstream_response_time"';

Условное логирование

access_log /var/log/nginx/access.log main if=$loggable;

Статистика через stub_status (требует `ngx_http_stub_status_module`)

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

Возвращает:

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

Безопасность

Ограничение методов

if ($request_method !~ ^(GET|HEAD|POST)$ ) {
    return 405;
}

Защита от hotlinking

location ~ \.(jpg|png|gif)$ {
    valid_referers none blocked server_names *.example.com;
    if ($invalid_referer) {
        return 403;
    }
}

CSP и безопасные заголовки

add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'";
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

Rate limiting для защиты от ботов

limit_req_zone $binary_remote_addr zone=bot_protect:10m rate=10r/m;
location / {
    limit_req zone=bot_protect burst=20 nodelay;
}

SSL/TLS: полная настройка

Базовые директивы

server {
    listen 443 ssl http2;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
}

ssl_certificate — должен содержать сертификат и цепочку промежуточных CA.
ssl_certificate_key — закрытый ключ в формате PEM.

OCSP Stapling

Позволяет клиенту проверить статус отзыва сертификата без обращения к CA.

ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
ssl_trusted_certificate /path/to/fullchain.pem;

ssl_trusted_certificate должен включать корневой и промежуточный сертификаты.
Требуется DNS-резолвер.

HSTS (HTTP Strict Transport Security)

Принудительно переключает клиент на HTTPS.

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

max-age=31536000 — один год.
includeSubDomains — применяется ко всем поддоменам.
preload — позволяет включить домен в список браузеров.

Let’s Encrypt

Автоматическая выдача и обновление сертификатов через Certbot.

Типичная интеграция:

Certbot обновляет файлы в /etc/letsencrypt/live/example.com/

Nginx ссылается на них:

ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

Обновление конфигурации после renewal:
```
nginx -s reload
```

HTTP/2 и HTTP/3 (QUIC)

HTTP/2

Включается добавлением параметра http2 к listen.

listen 443 ssl http2;

Требования:

Поддержка ALPN в OpenSSL (версия 1.0.2+)
SSL/TLS обязательны (HTTP/2 не работает по HTTP)

HTTP/3 (QUIC)

Поддерживается начиная с Nginx 1.25.0 (через экспериментальный модуль ngx_http_v3_module).

listen 443 quic reuseport;
listen 443 ssl http2;
http3 on;
http3_hq on;
ssl_protocols TLSv1.3;

Требует OpenSSL 3.0+ или BoringSSL.
Использует UDP вместо TCP.
Улучшает производительность при высокой задержке и потере пакетов.

На момент 2026 года HTTP/3 поддерживается большинством браузеров и CDN.

WebSocket-проксирование

WebSocket требует специальной настройки заголовков для установки upgrade-соединения.

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;  # 24 часа
}

$http_upgrade содержит значение заголовка Upgrade от клиента.
Connection "upgrade" сигнализирует бэкенду о переключении протокола.
Длинный proxy_read_timeout предотвращает разрыв «тихих» соединений.

Мониторинг и интеграция

stub_status (встроенный)

location /nginx_status {
    stub_status;
    allow 10.0.0.0/8;
    deny all;
}

Возвращает простой текстовый статус.

Prometheus + nginx-prometheus-exporter

Для полноценного мониторинга используется внешний экспортер, который парсит логи или использует stub_status.

Альтернатива — модуль ngx_http_vts_module (Virtual Host Traffic Status), предоставляющий JSON-статистику.

Логирование для аналитики

Добавление уникального ID запроса:

log_format trace '$request_id $remote_addr - $remote_user [$time_local] "$request" $status';
add_header X-Request-ID $request_id always;

Генерация request_id:

map $http_x_request_id $request_id {
    default $http_x_request_id;
    "" $msec-$pid-$connection;
}

Динамическая конфигурация

Перезагрузка без downtime

nginx -t && nginx -s reload

Проверка синтаксиса перед reload обязательна.
Рабочие процессы завершаются только после завершения текущих соединений.

API (Nginx Plus)

В коммерческой версии доступен REST API для управления upstream, key-value хранилищем, мониторингом.

Open source аналогов нет, но можно использовать:

Lua-модуль (ngx_http_lua_module) для динамических решений
Внешние скрипты, генерирующие конфиг и вызывающие reload

Ошибки и диагностика

Распространённые ошибки

Ошибка	Причина	Решение
`403 Forbidden`	Нет прав на файл или директорию	Проверить владельца, права (`chmod`, `chown`)
`404 Not Found`	Файл не найден по пути `root`/`alias`	Проверить путь, `try_files`
`502 Bad Gateway`	Бэкенд недоступен	Проверить `upstream`, порт, firewall
`504 Gateway Timeout`	Бэкенд не ответил вовремя	Увеличить `proxy_read_timeout`
`client intended to send too large body`	Превышен `client_max_body_size`	Увеличить лимит

Логирование ошибок

error_log /var/log/nginx/error.log debug;

Уровень debug требует сборки Nginx с --with-debug.

Проверка конфигурации

nginx -t
# или
nginx -T  # выводит полную конфигурацию

Справочник по Nginx​

Уровни конфигурации (контексты)​

1. Главный контекст (main)​

Пример:​

Директивы главного контекста​

user​

worker_processes​

worker_connections​

error_log​

pid​

worker_rlimit_nofile​

worker_cpu_affinity​

timer_resolution​

worker_priority​

ssl_engine​

2. Контекст events​

Пример:​

Директивы блока events​

worker_connections​

use​

multi_accept​

accept_mutex​

accept_mutex_delay​

debug_connection​

3. Контекст http​

Пример:​

Директивы блока http​

include​

default_type​

types​

log_format​

access_log​

sendfile​

tcp_nopush​

tcp_nodelay​

keepalive_timeout​

keepalive_requests​

reset_timedout_connection​

server_tokens​

client_max_body_size​

client_body_buffer_size​

client_body_temp_path​

client_header_buffer_size​

large_client_header_buffers​

client_body_in_file_only​

gzip​

gzip_vary​

gzip_min_length​

gzip_comp_level​

gzip_types​

gzip_proxied​

gzip_disable​

open_file_cache​

open_file_cache_valid​

open_file_cache_min_uses​

open_file_cache_errors​

resolver​

resolver_timeout​

variables_hash_max_size​

variables_hash_bucket_size​

server_names_hash_max_size​

server_names_hash_bucket_size​

map​

geo​

limit_conn_zone​

limit_req_zone​

upstream​

Блок server​

Контекст​

Пример базового сервера:​

Основные директивы блока server​

listen​

server_name​

root​

index​

error_page​

try_files​

client_max_body_size​

ssl_certificate и ssl_certificate_key​

ssl_protocols, ssl_ciphers, ssl_prefer_server_ciphers​

Справочник по Nginx

Уровни конфигурации (контексты)

1. Главный контекст (`main`)

Пример:

Директивы главного контекста

`user`

`worker_processes`

`worker_connections`

`error_log`

`pid`

`worker_rlimit_nofile`

`worker_cpu_affinity`

`timer_resolution`

`worker_priority`

`ssl_engine`

2. Контекст `events`

Пример:

Директивы блока `events`

`worker_connections`

`use`

`multi_accept`

`accept_mutex`

`accept_mutex_delay`

`debug_connection`

3. Контекст `http`

Пример:

Директивы блока `http`

`include`

`default_type`

`types`

`log_format`

`access_log`

`sendfile`

`tcp_nopush`

`tcp_nodelay`

`keepalive_timeout`

`keepalive_requests`

`reset_timedout_connection`

`server_tokens`

`client_max_body_size`

`client_body_buffer_size`

`client_body_temp_path`

`client_header_buffer_size`

`large_client_header_buffers`

`client_body_in_file_only`

`gzip`

`gzip_vary`

`gzip_min_length`

`gzip_comp_level`

`gzip_types`

`gzip_proxied`

`gzip_disable`

`open_file_cache`

`open_file_cache_valid`

`open_file_cache_min_uses`

`open_file_cache_errors`

`resolver`

`resolver_timeout`

`variables_hash_max_size`

`variables_hash_bucket_size`

`server_names_hash_max_size`

`server_names_hash_bucket_size`

`map`

`geo`

`limit_conn_zone`

`limit_req_zone`

`upstream`

Блок `server`

Контекст

Пример базового сервера:

Основные директивы блока `server`

`listen`

`server_name`

`root`

`index`

`error_page`

`try_files`

`client_max_body_size`

`ssl_certificate` и `ssl_certificate_key`

`ssl_protocols`, `ssl_ciphers`, `ssl_prefer_server_ciphers`